** README for U.S. Dates of Municipal Incorporation Dataset
** Author: Kiara Wyndham-Douds
** Date: July 11, 2022


/*OVERVIEW
The code in this package cleans and appends two data sources with information on
year of incorporation for U.S. municipalities: the 1987 Census of Governments (COG) 
and the 1987-2019 Boundaries and Annexation Survey (BAS) from the Census. To my 
knowlege, these data sources together provide the most complete record of dates
of incorporation for U.S. municipalities.

Because of the data  used, the resulting data contain information for year of 
incorporation for all incorporated municipalities in existence from 1987 or later.
Municipalities that incorporated then subsequently merged with another municipality, 
un-incorporated, or were annexed into another municipality prior to 1987 are not 
included. Further, roughly 3,000 municipalities were missing information on year
of incorporation in the 1987 COG, so they are also missing from the final dataset.

A time-consistent unique geographic identifier - NHGISPLACE - created by the folks
at IPUMS NHGIS is provided with the final dataset so that these data can be merged 
with data files from varying time points. To match Census place FIPS codes to NGHISPLACE
codes, download the GIS Place Point file from IPUMS NHGIS for the closest Census year.
*/

/*DATA AVAILABILITY

All data used in this package are publicly available. I include some cleaned
versions of the data in the package; in other places, I note the source in the code. 

Data sources:
1. 1987 Census of Governments: https://www.census.gov/programs-surveys/gov-finances/data/historical-data.html
	- As of 7.2022, available in vaguely named zip file "4_Govt_Org_Directory_Surveys" at link above. 
		Files available as Microsoft Access files. I converted to Excel and include 
		converted files here in dataset.
	- Datafile: "QQ01_ General Purpose Data for 1987.xlsx"
2. 1987-2019 Boundary and Annexation Survey: https://www.census.gov/geographies/reference-files/time-series/geo/bas/new-annex.html
	- As of 7.2022, data files available at link above as Excel files for each decade. 
		Files include new incorporations as well as annexations, mergers, and 
		other new entities. I include versions of these raw data files ready for
		import into Stata or another statistical program in this archive (formatting
		is removed and variable names changed to match requirements by Stata).
	-Datafiles: new_incs_1980-1989_forstata.xlsx, new_incs_1990-1999_forstata.xlsx,
		2000-2009entitychanges_forstata.xlsx, 2010-2019entitychanges_forstata.xlsx
3. IPUMS NHGIS Place Point Data: https://www.nhgis.org/documentation/gis-data/place-points#identifiers
	- As of 7.2022, place point data are available once an account is created
		for free with IPUMS. I use Place Point GIS data here for multiple decades, 
		which can be found using the site's "Select Data" tool. 
*/

/*DATASET LIST
See dataset_list.csv
*/

/*COMPUTATIONAL REQUIREMENTS
Stata (code was last run wtih version 17)
*/

/*DESCRIPTION OF CODE
- incorp-clean01-cog.do cleans 1987 COG data file and merges in time-consistent geographic ID - NGHISPLACE
- incorp-clean02-bas.do cleans BAS data and merges in time-consistent geographic ID - NGHISPLACE
- incorp-clean03-append.do appends cleaned COG and BAS data files to create
	final data file: muni_yr_incorp.csv
*/

/*INSTRUCTIONS TO REPLICATORS
1. Download data files referenced above as well as code. 
2. Download IPUMS NHGIS Place Point GIS files (instructions above).
3. Run do files in sequential order to replicate creation of muni_yr_incorp.csv
*/


